home *** CD-ROM | disk | FTP | other *** search
/ TeX 1995 July / TeX CD-ROM July 1995 (Disc 1)(Walnut Creek)(1995).ISO / web / fweb / fweb-1.40 / manual / guide0.tex (.txt) < prev    next >
LaTeX Document  |  1993-10-29  |  63KB  |  1,340 lines
  1. % --- guide0.tex ---
  2. % FWEB reference guide.  Included either by guide.tex (stand-alone guide)
  3. % or fwebman.tex (the complete user's manual).
  4. \FWEB\ is available ^^[\>{FWEB}!obtaining]
  5. via anonymous guest \.{ftp} from Internet host
  6. \.{lyman.pppl.gov}, a Sun SparcStation running \Unix.  Use binary mode to
  7. transfer a compressed \.{tar} file with a name like \.{fweb-1.30.tar.Z}.
  8. See the file \.{/pub/fweb/READ\_ME} for the current status, recent bug
  9. reports, and further instructions.
  10. For those without \.{ftp} access, it is possible to emulate the function
  11. of~\.{ftp} 
  12. by sending a valid \.{ftp} session as a mail message to \.{bitftp@pucc.bitnet}.
  13. The requested files will be returned by mail, possible \.{uuencode}d  and
  14. broken up into several parts if they are sufficiently long.  A sample \.{ftp}
  15. session is
  16. {\codemode
  17. ftp lyman.pppl.gov
  18. cd /pub/fweb
  19. get READ_ME
  20. \noindent To learn more about the \.{bitftp} service, send a message
  21. containing the single word ``\.{help}'' to the above address.
  22. To unpack the \.{tar} file, say
  23. {\codemode
  24. uncompress fweb-1.30.tar
  25. tar -xvf fweb-1.30.tar
  26. A brief summary of the installation procedure can be found in the
  27. \.{READ\_ME.FWEB} file included in the subdirectory corresponding to the
  28. numbered release---e.g., \.{/pub/fweb/v1.30/READ\_ME.FWEB}.  \Unix\ users
  29. should do the following:
  30. {\codemode
  31. cd fweb-1.30
  32. ./configure
  33. cd web
  34. make bootstrap
  35. make install
  36. More detailed installation information can be found in the separate file
  37. \.{INSTALL\_FWEB.tex} ^^:\>{INSTALL\UL FWEB.tex}: included with the \FWEB\
  38. release in the \.{manual} subdirectory.
  39. \vfill\Eject
  40. % ------------------------------ SYNTAX SUMMARY ------------------------------
  41. \def\sectionbreak{\filbreak\bigskip}
  42. \appendix L: SYNTAX SUMMARY.[][19.12.20]
  43. ^^(syntax!summary(
  44. Here we summarize various of the important features of \FWEB.
  45. This material is intended to be for reference; please refer to the body of
  46. the user's manual for full details.
  47. ^^[syntax!summary]
  48. \parskip=0pt plus1pt
  49. \long\def\summarize#1#2#3\par#4\par{\par{%
  50. \def\[##1]{[\.{##1}]}\def\(##1){(##1)}%
  51. \def\snext{#3}
  52. \ifx\snext\empty\def\starttext{}
  53.     \else\def\starttext{#3\medskip}\fi
  54. \subsubsection #1.\par\starttext
  55. \abovedisplayskip=0pt plus1pt
  56. $$\vbox{\halign{\quad\tt##\hfil&--- \ 
  57. \vtop{\hsize=#2\hsize\noindent\hang\strut\ignorespaces##\strut}\hfil\cr
  58.         #4}}$$}}
  59. \def\Item{\itemitem{$\bullet$}}
  60. ^^{\>{WEB}!phases of}
  61. \summarize{The \FWEB\ processors}{0.7}
  62. FTANGLE & \It{Creates compilable code}.\endgraf
  63. \medskip
  64. \leftline{\bf Phase one:}^^{phase!1}
  65. \Item discards \TeX\ documentation;
  66. \Item tokenizes source;
  67. \Item expands~\.{@'\dots'}, \.{@"\dots"}, and \.{0b\It{binary}} (also
  68. \.{0\It{octal}} and \.{0x\It{hex}} in \Fortran);
  69. \Item stores code text in appropriate modules;
  70. \Item memorizes macro definitions (\.{@d} and~\.{@m}).\endgraf
  71. \medskip
  72. \leftline{\bf Phase two:}^^{phase!2}
  73. \Item outputs outer macro definitions (\.{@d});
  74. \Item outputs the unnamed module (\.{@a});
  75. \Item expands \WEB\ macros (\.{@m});
  76. \Item expands build-in macros;
  77. \Item translates \Ratfor\ statements.\endgraf
  78. FWEAVE & \It{Typesets the documentation and code}.\endgraf
  79. \medskip
  80. \leftline{\bf Phase one:}^^{phase!1}
  81. \Item tokenizes and stores identifiers and module names;
  82. \Item collects cross-reference information (including processing~\.{@[}
  83. and~\.{@\`});
  84. \Item stores limbo text definitions (\.{@l});
  85. \Item collects information about overloaded operators~(\.{@v}) and
  86. identifiers~(\.{@W}).\endgraf 
  87. \medskip
  88. \leftline{\bf Phase two:}^^{phase!2}
  89. \Item outputs limbo text;
  90. \Item outputs special \TeX\ macros for overloaded operators;
  91. \Item copies \TeX\ material directly to output;
  92. \Item treats material between vertical bars (\.{|\dots|}) as code to be
  93. typeset; 
  94. \Item tokenizes and stores contents of each code section;
  95. \Item analyzes code syntax and converts to appropriate \TeX\ macros.\endgraf
  96. \medskip
  97. \leftline{\bf Phase three:}^^{phase!3}
  98. \Item typesets index and  module cross-references;
  99. \Item writes table of contents.\endgraf
  100. \def\Oname(#1,#2){\It{name}.#1 {\rm (}#2{\rm)}}
  101. \summarize{Files}{0.7}  The \FWEB\ system works with a variety of files.
  102. File names have the form \It{[path]}\./\It{root}\It{[.ext]}.  Here '\./'
  103. is called the \\{PREFIX\_END\_CHAR}.  ^^:\>{PREFIX\UL END\UL CHAR}:
  104. Since it differs for various operating systems, it can be changed in
  105. \.{custom.h}.  
  106. ^^{customizing!directory path specifications} ^^{\>{custom.h}}
  107. The character that initiates the file-name extension (normally a period)
  108. can be changed with the `\.{-E}'~command-line option. ^^{\={-e}{-E}}
  109. \subheading{Input files:}
  110. \It{null file}&The system sometimes reads from the null file.  This name
  111. varies from system to system; the default can be defined in \.{custom.h},
  112. or it can be changed with the style-file parameter \.{null\_file}.
  113. ^^{file!null} ^^{customizing!null-file name}
  114. ^^{style file!vocabulary!\>{null\UL file}}\cr
  115. .fweb{\rm\ (or }fweb.ini{\rm)} & Initialization file; always in the
  116. \It{home} directory. 
  117. ^^{directory!home}
  118. The basic file name can be overridden by the environment variable
  119. \.{FWEB\_INI}. ^^{\>{FWEB\UL INI}} (It can also be changed in \.{custom.h},
  120. although this is strongly discouraged.)\cr 
  121. fweb.sty & Style file; in \It{current} directory ^^{directory!current}
  122. unless overridden by
  123. environment variable \.{FWEB\_STYLE\_DIR}.  ^^{\>{FWEB\UL STYLE\UL DIR}}
  124. The basic name can be changed by
  125. the `\.{-z}'~option. ^^{\>{-z}} (It can also be changed in \.{custom.h},
  126. although this is strongly discouraged.)\cr
  127. \It{name}.web & Source code.  (Alternative suffixes can be searched for
  128. automatically with the `\.{-e}'~option and the \.{ext.web} style-file entry.)
  129. ^^{\>{-e}} ^^{style file!vocabulary!\>{ext.web}}\cr
  130. \It{name}.ch & Change file.  (Suffixes are treated as above, but see
  131. \.{ext.change}.) 
  132. ^^{style file!vocabulary!\>{ext.change}}\cr 
  133. \It{name}.hweb & Code included into \.{web} file with~\atcmd{i}. Include
  134. files are searched for in the path set by the environment variable
  135. \.{FWEB\_INCLUDES} ^^{\>{FWEB\UL INCLUDES}} ^^{path!for include files}
  136. and/or the \.{-I}~option; ^^{\={-i}{-I}}
  137. if that path is empty, then the current directory is searched. (Suffixes
  138. are treated as above, but see \.{ext.hweb}.) ^^{style
  139. file!vocabulary!\>{ext.hweb}}\cr 
  140. \It{name}.hch & Change file for include file.  (Suffixes are treated as
  141. above, but see \.{ext.hchange}.) ^^{style file!vocabulary!\>{ext.hchange}}\cr 
  142. \subheading{Output files:}
  143. \It{name}.tex & Woven output; can be processed with either Plain \TeX\ or
  144. \LaTeX.\cr 
  145. \noalign{\smallskip}
  146. CONTENTS.tex & Accumulates table-of-contents information written by
  147. \FWEAVE.  (This name can be overridden by the style-file option
  148. \.{contents.tex}.) 
  149. ^^{\>{CONTENTS.tex}} ^^{style file!vocabulary!\>{contents.tex}}\cr 
  150. INDEX.tex & Stores indexing information written by \FWEAVE.  (This name can
  151. be overridden by the style-file option \.{index.tex}.) 
  152. ^^{\>{INDEX.tex}} ^^{style file!vocabulary!\>{index.tex}}\cr
  153. MODULES.tex & Stores module list written by \FWEAVE.  (This name can be
  154. overridden by the style-file option \.{modules.tex}.) 
  155. ^^{\>{MODULES.tex}} ^^{style file!vocabulary!\>{modules.tex}}\cr
  156. \noalign{\smallskip}
  157. \It{name.ext} & Compilable output file; see table below for the extension
  158. associated with each language.\cr
  159. \indent When the `\.{-e}'~option is in effect, ^^{\>{-e}}
  160. input file names that include no
  161. period are completed automatically according to the style-file entries
  162. listed in the following table:
  163. ^^:file name!extensions:
  164. $$\vbox{\offinterlineskip
  165. \halign{\vrule\vrule#&\strut\quad#\quad\hfil&\vrule#&\hfil\quad\tt#\quad\hfil
  166.     &\vrule#&\hfil\quad\tt#\quad\hfil&\vrule\vrule#\cr\tablerule\tablerule
  167. &\It{Type of file}&&\It{Style-file entry}&&\It{Default}&\cr
  168. \tablerule\tablerule 
  169. &\WEB\ file&&ext.web&&.web&\cr\tablerule
  170. &Change file&&ext.ch&&.ch&\cr\tablerule
  171. &Include file&&ext.hweb&&.hweb&\cr\tablerule
  172. &$\vcenter{\hbox{\strut Change file}\hbox{for include
  173. file\strut}}$&&ext.hch&&.hch&\cr \tablerule\tablerule
  174. The default extension for the file(s) output by \FTANGLE\ sometimes depends on
  175. whether the operating system is \Unix\ or not.  (These defaults can be
  176. overridden by style-file parameters, as indicated.)
  177.  ^^{extensions!file-name}
  178.  ^^{style file!vocabulary!\>{suffix.C}}
  179.  ^^{style file!vocabulary!\>{suffix.Cpp}}
  180.  ^^{style file!vocabulary!\>{suffix.N}}
  181.  ^^{style file!vocabulary!\>{suffix.N90}}
  182.  ^^{style file!vocabulary!\>{suffix.K}}
  183.  ^^{style file!vocabulary!\>{suffix.R}}
  184.  ^^{style file!vocabulary!\>{suffix.R90}}
  185.  ^^{style file!vocabulary!\>{suffix.X}}
  186. $$\vbox{\offinterlineskip
  187. \halign{\vrule\vrule#&\strut\quad#\quad\hfil&\vrule#
  188.     &\quad\tt#\quad\hfil&\vrule#%
  189.     &\hfil\quad\tt#\quad\hfil&\vrule#%
  190.     &\hfil\quad\tt#\quad\hfil&\vrule\vrule#\cr\tablerule\tablerule
  191. &\hfil\It{Language}&&\hfil\It{Style-file
  192. entry}&&$\vcenter{\it\hbox{\strut \Unix}\hbox{default\strut}}$ 
  193. &&$\vcenter{\it\hbox{\strut Non-\Unix}\hbox{default\strut}}$&\cr 
  194. \tablerule\tablerule 
  195. &\tt C&&suffix.C&&.c&&.c&\cr\tablerule
  196. &\tt \Cpp&&suffix.Cpp&&.c++&&.cpp&\cr\tablerule
  197. &\tt FORTRAN--77&&suffix.N&&.f&&.for&\cr\tablerule
  198. &\tt FORTRAN--90&&suffix.N90&&.f&&.for&\cr\tablerule
  199. &\tt MAKE&&suffix.K&&.mk&&.mk&\cr \tablerule
  200. &\tt RATFOR--77&&suffix.R&&.f&&.for&\cr\tablerule
  201. &\tt RATFOR--90&&suffix.R90&&.f&&.for&\cr\tablerule
  202. &\tt TEX&&suffix.X&&.sty&&.sty&\cr\tablerule\tablerule
  203. \summarize{Environment variables}{0.7}
  204. Environment variables ^^{environment variables} in \Unix\ and logical names
  205. in VMS behave in the same way. 
  206. FWEB\_INCLUDES &^^{\>{FWEB\UL INCLUDES}} Colon-delimited list (identical in
  207.   format to the Unix C-shell \.{PATH} variable)  of
  208.   directories to search for include files. ^^{path!for include files}
  209.   (One can append to this list by means of the \.{-I}~option.) ^^{\={-i}{-I}}
  210.   ^^{environment variables!\>{FWEB}!\>{FWEB\UL INCLUDES}}
  211.   \cr
  212. FWEB\_INI &^^{\>{FWEB\UL INI}} Name of the initialization file---e.g.,
  213.   \.{fweb.ini}.  If not defined, either \.{.fweb} or~\.{fweb.ini} is chosen,
  214.   depending on the machine.  The initialization file always resides in
  215.   \.{\$HOME}. ^^{\>{.fweb}} ^^{\>{fweb.ini}}
  216.   ^^{environment variables!\>{FWEB}!\>{FWEB\UL INI}}
  217.   \cr 
  218. FWEB\_STYLE\_DIR &^^{\>{FWEB\UL STYLE\UL DIR}} Directory in which style file
  219.   resides---e.g., \.{\$HOME/fweb}.  If not defined, the current directory is
  220.   used.
  221.   ^^{environment variables!\>{FWEB}!\>{FWEB\UL STYLE}}
  222.   \cr 
  223. HOME &^^{\>{HOME}} Name of the home directory.  This variable should be
  224.   defined by \Unix.
  225.   ^^{environment variables!Unix!\>{HOME}}
  226.   \cr
  227. TERM &^^{\>{TERM}} The terminal type.  Defined by \Unix.
  228.   ^^{environment variables!Unix!\>{TERM}}
  229.   \cr
  230. \indent To change an environment variable, say, for example (in \Unix)
  231. {\codemode
  232. setenv FWEB_INCLUDES .:$HOME/fweb:/usr/xxx/stuff
  233. setenv FWEB_INI my_FWEB.ini
  234. \noindent For VMS, substitute ``\.{define}'' for ``\.{setenv}''.
  235. \medskip
  236. The built-in function \.{\_GETENV(\It{ENV})} expands to the value of the
  237. environment variable~\\{ENV}.
  238. ^^{environment variable!obtaining value of}
  239. \subsubsection Order of initial operations.
  240. \FWEB\ begins its processing by performing the following operations:
  241. ^^[processing!order of]
  242. {\narrower\newfeature
  243. \medskip
  244. \feature. Evaluate environment variables.
  245. \feature. Read initialization file \.{.fweb}.
  246. \feature. Execute \.{.fweb} options beginning with~'\.+'.
  247. \feature. Read and execute the command line.
  248. \feature. Execute remaining \.{.fweb} options.
  249. \feature. Read the style file \.{fweb.sty}.
  250. \feature. Process the \WEB\ file.
  251. \def\arg#1{{\it[#1]}}
  252. \summarize{Command-line syntax}{0.7}
  253. ^^{syntax!command-line} ^^{command line!syntax}
  254. The command-line syntax is
  255. $$\left\{\matrix{\hbox{\FWEAVE}\cr\hbox{\FTANGLE}\cr}\right\}
  256. \hbox{ \It{web\_file\_name} [\It{change\_file\_name}] [\It{options}]}
  257. where the command-line options, 
  258. ^^{options, command-line} ^^{command line!options} 
  259. each of which must begin with a hyphen,
  260. are summarized below.  (Actually, the options can appear before the file
  261. names, or can even be intermixed with them.)  If an option has an argument,
  262. no space should precede the argument.  (E.g., say ``\.{-zmy.sty}'', not
  263. ``\.{-z\ my.sty}''.)  In the descriptions of the options,
  264. the letters~\.T or~\.W in brackets denotes to which
  265. processor the command applies; no brackets at all means it applies to both
  266. processor. Similarly, parenthesized~\.C, \.N, \.R, or~\.X denotes the
  267. applicable 
  268. language. Italic brackets, as in \.{-d}\It{[nnnnn]}, indicate an optional
  269. argument; the brackets themselves shouldn't be typed. Stars mean the
  270. command is \It{not} allowed to be optionally changed along with a language
  271. change, according to the format `\atcmd{$l$[\It{options}]}' or
  272. `\atcmd{L$l$[\It{options}]}'. 
  273. \summarize{Command-line options {\tt a}--{\tt q}}{0.7}
  274. -0 &^^{\>{-0}} Turn off \WEAVE's debugging mode.  \[W]. 
  275.     ^^{debugging!turning off}\cr 
  276. -1 &^^{\>{-1}} Turn on brief debugging mode. (Display irreducible scraps.)
  277.     \[W]. ^^{debugging!turning on!limited}\cr 
  278. -2 &^^{\>{-2}} Turn on verbose debugging mode. (Display detailed reductions
  279.     of the scraps.) \[W]. ^^{debugging!turning on!verbose}\cr
  280. -A &^^{\={-a}{-A}} Turn on \&{ASCII} translations. ^^{ASCII!turning on
  281.     translations to}\cr
  282. -b &^^{\>{-b}} Number \&{do} and \&{if}~blocks in woven \Fortran\ and \Ratfor\
  283.     output.  \[W]. ^^{block numbers}\cr
  284. \lstar -c &^^{\>{-c}} Set the global language to~C. ^^{language!global!C}\cr
  285. \lstar -c++ &^^{\>{-c++}} Set the global language to~\Cpp.
  286.     ^^{language!global!\Cpp}\cr 
  287. -D\It{[letters]}&^^{\={-d}{-D}} Display information about reserved words of the
  288.     current language (beginning with \It{letters} if present).
  289.     ^^{reserved words!displaying}\cr
  290. -d\It{[nnnnn]} &^^{\>{-d}} Convert unnumbered `\.{do\dots enddo}'
  291.     constructions to standard \Fortran--77.  \[T]; \(N). 
  292.     ^^{\<{do}!numbering}\cr
  293. -E$c$ &^^{\={-e}{-E}} Change the delimiter of a file-name extension from the
  294.     default~'\..' to~$c$.
  295.     ^^{extensions!file-name!changing delimiter for}\cr
  296. -e &^^{\>{-e}} Turn on automatic file-name completion.  (See discussion of
  297.     the style file entries \.{ext.*}.) ^^{file name!automatic
  298.     completion of}\cr
  299. -f &^^{\>{-f}} Turn off module references for identifiers.  \[W].
  300.     ^^{module!references!turning off}\cr
  301. \lstar -h &^^{\>{-h}} Get help from the command line. \It{(Not implemented
  302.     yet.)} ^^{help!command line}\cr 
  303. -I\It{directory} &^^{\={-i}{-I}} Append a directory or colon-delimited list
  304.     of directories to the list of directories to be searched for include
  305.     files. \cr 
  306. -i &^^{\>{-i}} Read include files named by the \atcmd{I}~command, but
  307.     do not print their contents.  \[W]. ^^{file!including!not
  308.     printing}\cr 
  309. -i! &^^{\>{-i"!}} Don't even read include files named by the
  310.     \atcmd{I}~command. \[W]. \cr   
  311. \lstar -L\It{l} &^^{\={-l}{-L{\it l}}} Select global language: $l \in
  312.     \{\.c,\.n,\.r,\.x\}$. 
  313.     ^^{language!selecting}\cr 
  314. -l\It{[mmm[:nnn]]} &^^{\>{-l}} Echo the input line constructed by the
  315.     input driver between lines~\It{mmm} and~\It{nnn}.
  316. ^^{debugging!echoing input lines}\cr
  317. \lstar -m\It{id[=text]} &^^{\>{-m}} Define a \WEB\ macro.  \[T]. \cr
  318. -m4 &^^{\>{-m4}} Understand the \.{m4} built-in commands.  \[W].
  319.     ^^{\>{m4}!understanding commands of}\cr
  320. -m; &^^{\>{-m;}} Automatically append a pseudo-semicolon to \WEB\ macro
  321.     definitions. \[W]. ^^{pseudo-!semicolon!appending automatically}\cr 
  322. \lstar -n &^^{\>{-n}} Set the global language to \Fortran--77.
  323.     ^^{language!global!Fortran--77\actual\FORTRAN--77}\cr 
  324. \lstar -n9 &^^{\>{-n9}} Set the global language to \Fortran--90.
  325.     ^^{language!global!Fortran--90\actual\FORTRAN--90}\cr 
  326. -n; &^^{\>{-n;}} For \Fortran--77, supply semicolons automatically.
  327.     (Default mode.) ^^{semicolons!automatic!Fortran:\FORTRAN}\cr
  328. -nb &^^{\>{-nb}} In \Fortran, number the \&{if}s and \&{do}s.  \[W]; \(N). 
  329.     ^^{block numbers!\Fortran}\cr
  330. -np &^^{\>{-np}} Print semicolons in woven \Fortran\ output.  \[W].
  331.     ^^{semicolons!printing}\cr 
  332. -n\BS &^^{\>{-n\BS}} Select free-form \Fortran--90 syntax continued with a
  333.     backslash. ^^{syntax!free-form!continuing with backslash}\cr 
  334. -n\amp & ^^{\>{-n\amp}} As above, but continue with an ampersand.
  335.     ^^{syntax!free-form!continuing with ampersand}\cr
  336. -n/ &^^{\>{-n/}} In \Fortran, make '\.{//}'~denote the start of
  337.     a short comment instead of  concatenation.  (One can always
  338.     use~'\.{\\/}' for concatenation.) ^^{comment!short!recognizing in
  339.     \FORTRAN}\cr 
  340. -n! &^^{\>{-n"!}} In \Fortran, make
  341.     `\.!'~denote the start of a short comment instead of the logical
  342.     \.{NOT}.\cr 
  343. -o &^^{\>{-o}} Turn off \FWEAVE's mechanisms for overloading operators. \[W].
  344.     ^^{operator!overloading!turning off}\cr
  345. \lstar -P\It{letter} &^^{\={-p}{-P}} Selects the \TeX\ processor for \FWEAVE's
  346.     output.  Say~`\.{-PL}' for \LaTeX; the default is~`\.{-PT}' for \TeX.
  347.     \[W].
  348.     ^^{\TeX\ processor, selecting}
  349.     ^^{processor!\TeX} ^^{processor!\LaTeX}
  350. \lstar -p\It{styleentry} &^^{\>{-p}} Buffer up a style-file entry, to be
  351.     processed just before the local style file is read.
  352.     ^^{style file!global entry}\cr
  353. -q &^^{\>{-q}} Do \It{not} translate \Ratfor\ commands into \Fortran.  (No
  354.     longer supported.) \[T]; \(R). \cr
  355. \summarize{Command-line options {\tt r}--{\tt z}}{0.7}
  356. \lstar -r &^^{\>{-r}} Set the global language to \Ratfor--77.
  357.     ^^{language!global!Ratfor--77:\RATFOR--77}\cr 
  358. \lstar -r9 &^^{\>{-r9}} Set the global language to \Ratfor--90.
  359.     ^^{language!global!Ratfor--90:\RATFOR--90}\cr 
  360. -rb &^^{\>{-rb}} In \Ratfor, number the \&{if}s and \&{do}s.  \[W]; \(N). 
  361.     ^^{block numbers!\Ratfor}\cr
  362. -rg\It{params} &^^{\>{-rg}} Set the \&{goto} parameters for \Ratfor's
  363.     \&{switch}. \[T]; \(R).\cr 
  364. -rk\It{[letters]} &^^{\>{-rk}} Suppress particular comments about \Ratfor\
  365.     statement translation.  \[T]; \(R).
  366.     ^^{Ratfor:\RATFOR!commands!deleting}\cr 
  367. -rK\It{[letters]} &^^{\={-rk}{-rK}} As above, but write out particular
  368.     comments. \[T]. \cr 
  369. -r; &^^{\>{-r;}} Turns on \Ratfor's auto-semi mode, and tells it to
  370.     use the ``obviously continued'' syntax.  \(R).
  371.     ^^{semicolons!automatic!Ratfor:\RATFOR}\cr
  372. -r/ &^^{\>{-r/}} In \Ratfor, make `\.{//}'~denote the start of
  373.     a short comment instead of  concatenation.  (One can always
  374.     use~'\.{\\/}' for concatenation.)  \(R).
  375.     ^^{comment!short!recognizing in \RATFOR}\cr
  376. -r!&^^{\>{-r"!}} In \Ratfor, make `\.!'~denote the start of a short comment
  377.     instead of the logical \.{NOT}. \cr 
  378. \lstar -s &^^{\>{-s}} Print statistics about memory usage. ^^{statistics}\cr
  379. \lstar -sm\It{[nnn]} &^^{\>{-sm}} As above, but also display the dynamic
  380.     memory     allocations of size $\ge$~\It{nnn} as they occur.
  381.     ^^{memory, dynamic allocation of!statistics for}\cr
  382. \lstar -t\It{ln[\{\dots\}]} &^^{\>{-t}} Truncate identifiers of
  383.     language~$l$ to length~$n$, after optionally filtering out the
  384.     characters listed between the braces. \[W].\cr
  385. \lstar -u\It{id} &^^{\>{-u}} Undefine a predefined or command-line macro.
  386.     \[T]. ^^{macro!outer!undefining}\cr 
  387. -v &^^{\>{-v}} Make all comments verbatim.  \[T].
  388.     ^^{comment!verbatim!making all}\cr
  389. -W\It{letters} &Commands that apply only to \FWEAVE.  Here \It{letters} may
  390.     be one or more of the following:
  391.     \clo{
  392.     [&^^{\={-w[}{-W[}} Turn on special processing of bracketed array
  393.         indices.\cr 
  394.     f&^^{\={-wf}{-Wf}} Don't print format statements (\.{@f}) in woven
  395.         output.\cr
  396.     l&^^{\={-wl}{-Wl}} As above, but for limbo statements (\.{@l}).\cr
  397.     m&^^{\={-wm}{-Wm}} As above, but for macro definitions (\.{@m}).\cr
  398.     v&^^{\={-wv}{-Wv}} As above, but for operator overloading 
  399.         (\.{@v}).\cr     
  400.     w&^^{\={-ww}{-Ww}} As above, but for identifier overloading
  401.         (\.{@W}).\cr
  402.     \noalign{\vskip-5pt}
  403.     }\cr
  404. \lstar -w\It{[file\_name]} &^^{\>{-w}} If \It{file\_name}~is absent,
  405.     don't print `\.{\\input\ fwebmac.sty}' as the first line of the
  406.     \.{TEX} output file.   Otherwise, print `\.{\\input
  407.     \It{file}\_\It{name}}'. \[W].     ^^{\>{fwebmac}!\>{.sty}!not
  408.     printing}\cr
  409. \lstar -X\It{[letters]} &^^{\={-x}{-X}} Print selected cross-reference
  410.     information; the opposite of~`\.{-x}'.
  411.     ^^{cross-references!suppressing}
  412.     ^^{index!printing}
  413.     ^^{module list!suppressing}
  414.     ^^{table of contents!suppressing}\cr
  415. \lstar -x\It{[letters]} &^^{\>{-x}} Reduce or eliminate cross-reference
  416.   information.  The optional letters can be one of~'\.c',
  417.   '\.i', '\.m', or~'\.*', referring respectively to the table of contents,
  418.   index, module list, or all cross-reference information. \[W].
  419.       ^^{index!not printing}\cr 
  420. \lstar -y\It{[a[a]][nnnn]} &^^{\>{-y}} Override default for dynamic memory
  421.     allocation.  If \It{nnnn} is omitted, then
  422.     simply query the default instead of overriding it.  The simple
  423.     command~`\.{-y}' with no argument queries everything.
  424.     ^^{memory, dynamic allocation of!syntax}\cr 
  425. -Z\It{[letters]}&^^{\={-z}{-Z}} Display default values of style-file parameters
  426.     (starting with \It{letters} if present).
  427.     ^^{style file!parameters!default values of}\cr
  428. \lstar -z\It{[name]} &^^{\>{-z}} Override default style-file name.
  429.     ^^{style file!new name for}\cr
  430. \summarize{Command-line options (miscellaneous)}{0.7}
  431. -. &^^{\>{-.}} Don't recognize ``dot constants'' in \Fortran\ or \Ratfor.
  432.     ^^{constant!dot}\cr
  433. -\BS &^^{\>{-\BS}} Explicitly escape continued strings.
  434.     ^^{strings!continuing!with explicit escape}\cr
  435. -( &^^{\>{-(}} Continue parenthesized strings with backslashes.
  436.     ^^{strings!parenthesized!continuing}\cr 
  437. -:\It{[nnnnn]} &^^{\>{-":}} Set the starting automatic statement number.
  438.     \[T]. ^^{statement!number!setting}\cr 
  439. \lstar ->\It{[l=][name]} &^^{\>{->}} Redirect tangled output.
  440.     ^^{output!redirection}\cr 
  441. \lstar -= &^^{\>{-=}} Redirect tangled output. Synonymous with~`\.{->}'.
  442.     Easy to type under \Unix.\cr 
  443. -\# &^^{\>{-\PM}} Turn off comments about line numbers and module
  444.     names in tangled output. \[T] ^^{line numbers!turning off}\cr
  445. -+ &^^{\>{-+}} Don't interpret the compound assignment operators. \[T];
  446.     \(N,R). ^^{operators!compound assignment!not recognizing}\cr 
  447. -/ &^^{\>{-/}} In both \Fortran\ and \Ratfor, make `\.{//}'~denote the start of
  448.     a short comment instead of  concatenation.  (One can always
  449.     use~'\.{\\/}' for concatenation.)\cr
  450. -! &^^{\>{-"!...}} In both \Fortran\ and \Ratfor, make 
  451.     `\.!'~denote the start of a short comment instead of the logical
  452.     \.{NOT}.\cr 
  453. \noindent These command-line options may also be put into the ini file
  454. \.{.fweb}. 
  455. ^^{\>{.fweb}} 
  456. Options beginning with a plus sign are processed \It{before} the
  457. command-line options. Otherwise, they are processed after the command-line
  458. options. 
  459. {%\tracingall
  460. \summarize{Modules}{0.7}
  461. ^^[modules!summary of]
  462. \Item Module names are delineated by \.{@<\dots@>}.  
  463. ^^{section name!beginning!in code}
  464. \Item To reference a named module in a macro definition, say
  465. `\.{\#<\dots@>}' instead of \atcmd{<\dots@>}. 
  466. ^^{section name!beginning!in macro}
  467. \Item The unnamed module is begun by~\atcmd{A} or~\atcmd{a}.  (The latter
  468. command inserts an implicit~\atcmd{[}.) 
  469. \Item \FTANGLE\ outputs the unnamed module.  \It{(There must be at least one
  470. unnamed section, otherwise there will be no output!)}
  471. \TeX\ part & \It{Arbitrary \TeX\ documentation}.\endgraf
  472. \medskip
  473. \Item Begins with~\atcmd{*} or~\atcmd{\ }.
  474. \Item Change to code mode with~\.{|\dots|}.\endgraf
  475. definition part & \It{Macro definitions, formatting, limbo text, operator overloading, etc.}\endgraf
  476. \medskip
  477. \Item Begins with~\atcmd{m}, \atcmd{d}, \atcmd{f}, \atcmd{l}, \atcmd{v},
  478. or~\atcmd{\#...}.\endgraf 
  479. code part & \It{The source code.}\endgraf
  480. \medskip
  481. \Item Begins with~\atcmd{a} or~\atcmd{<}.
  482. \Item \TeX\ mode inside comments.
  483. \Item Ends with~\atcmd{*} or~\atcmd{\ }.  (The end of file is like 
  484. an~\atcmd{\ }.)\endgraf
  485. \subsubsection The simplest \WEB\ sources. 
  486. The absolutely simplest nontrivial \WEB\ source file is ``\.{@\ @a}''.  The
  487. next simplest is
  488. ^^[\>{WEB}!source file!simplest]
  489. {\codemode
  490. @* EMPTY.
  491. \noindent These have a null definition part as well as a null code part.  The
  492. simplest \Fortran--77 code is
  493. {\codemode
  494. @* FORTRAN.
  495. \Tab program main
  496. \Tab end
  497. \noindent The same code in \Ratfor\ is
  498. {\codemode
  499. @* RATFOR.
  500. program main
  501. \noindent The corresponding code in~C is
  502. {\codemode
  503. @* C.
  504. main()
  505. \summarize{Control codes allowed in \WEB\ files}{0.62} ^^[commands!control
  506. codes!in \>{WEB} source]
  507. \subheading{Literal control characters:}
  508. @@ &^^{\>{@@}} Insert the single character~\atcmd{}.\cr
  509. @| &^^{\>{@"|}} Insert a vertical bar (\TeX\ text only).  In code mode,
  510. this command means an optional line break; see the ``Spacing'' commands
  511. below. ^^{vertical bar, literal}\cr 
  512. \subheading{Beginning of module:}
  513. @\.\  &^^{\>{@\ }} Begin a new minor
  514. (unstarred) module. ^^{module!beginning!unstarred} \cr 
  515. @*\It{[n]} &^^{\>{@*}} Begin a new major (starred) module of level~$n$.
  516. ^^{module!beginning!starred} \cr  
  517. \subheading{Beginning of code part:}
  518. @< &^^{\>{@<...@>}} ^^{\>{@<}} Begin a module name.
  519. ^^{module!name!beginning} \cr  
  520. @> &^^{\>{@>}} End a module name. ^^{module!name!ending} \cr
  521. \medalign
  522. @A &^^{\={@a}{@A}} Begin the code part of an unnamed module.
  523. ^^{module!part!code} \cr  
  524. @a &^^{\>{@a}} Equivalent to `\atcmd{A@[}'.\cr
  525. \subheading{Control codes \.{b}--\.{z}:}
  526. @b &^^{\>{@b}} Insert a ^{breakpoint command} in a \WEB\ module.\cr
  527. \medalign
  528. @c &^^{\>{@c}} Set the language to~C. ^^{language!setting!C}\cr
  529. @c++ &^^{\>{@c++}} Set the language to~\Cpp. ^^{language!setting!\Cpp}\cr
  530. \medalign
  531. @D &^^{\={@d}{@D}} Define an outer macro. ^^{macro!outer!defining}\cr
  532. @d &^^{\>{@d}} Equivalent to `\atcmd{D@[}'.\cr
  533. \medalign
  534. @e &^^{\>{@e}} Invisible (pseudo-) expression.\cr
  535. @f &^^{\>{@f}} Format an identifier or module name.
  536. ^^{formatting!identifiers} ^^{formatting!module names}\cr
  537. \medalign
  538. @I &^^{\={@i}{@I}} Include a file, but don't print it out if the \.{-i}~option
  539. is used.\cr
  540. @i &^^{\>{@i}} Include a file. ^^{file!including}\cr
  541. \medalign
  542. @L$l$ &^^{\={@l}{@L{\it l}}} Set language to~$l$. ^^{language!setting}\cr
  543. @l &^^{\>{@l}} Specify limbo text. ^^{limbo!text}\cr
  544. \medalign
  545. @M &^^{\={@m}{@M}} Define a \WEB\ macro. ^^{macro!inner!defining}\cr
  546. @m &^^{\>{@m}} Equivalent to `\atcmd{M@[}'.\cr
  547. \medalign
  548. @n &^^{\>{@n}} Set the language to \Fortran--77. 
  549.     ^^{language!setting!Fortran--77:\FORTRAN--77}\cr
  550. @n9 &^^{\>{@n9}} Set the language to \Fortran--90.
  551.     ^^{language!setting!Fortran--90:\FORTRAN--90}\cr 
  552. \medalign
  553. @O &^^{\>{@O}} Open new output file (global scope).  
  554.     ^^{file!output!opening new}\cr 
  555. @o &^^{\>{@o}} Open new output file (local scope). 
  556.     ^^{file!output!opening new}\cr
  557. \medalign
  558. @r &^^{\>{@r}} Set the language to \Ratfor--77.
  559.     ^^{language!setting!Ratfor--77:\RATFOR--77}\cr 
  560. @r9 &^^{\>{@r9}} Set the language to \Ratfor--90. 
  561.     ^^{language!setting!Ratfor--90:\RATFOR--90}\cr
  562. \summarize{Control codes allowed in \WEB\ files, cont'd}{0.62}
  563. @u &^^{\>{@u}} Undefine an outer macro. ^^{macro!outer!undefining}\cr
  564. \medalign
  565. @v &^^{\>{@v}} Overload an operator. ^^{operators!overloading}\cr
  566. @W &^^{\>{@W}} Overload an identifier. ^^{identifiers!overloading}\cr
  567. \medalign
  568. @x &^^{\>{@x}} Terminates ignorable material (begun by~\atcmd{z} at beginning
  569. of source or include file). ^^{ignorable material!terminating}\cr
  570. @z &^^{\>{@z}} Begins ignorable material at beginning of source or include
  571. file. ^^{ignorable material!beginning}\cr
  572. \subheading{Conversion to ASCII:}
  573. @' &^^{\>{@'}} Convert single character to ASCII.
  574. ^^{ASCII!converting to}\cr
  575. @" &^^{\>{@""}} Convert string to ASCII.  (In \Fortran\ or \Ratfor, generate
  576. a call to the function named by the style-file field \.{ASCII\_fcn}.)
  577. ^^{ASCII!converting to}\cr
  578. \subheading{Markers for forward referencing:}
  579. @[ &^^{\>{@[}} Mark the next identifier as defined in this module.
  580. ^^{identifiers!marking as defined}\cr
  581. @] &^^{\>{@]}} \It{Reserved}; do not use.\cr
  582. @` &^^{\>{@`}} \It{Reserved}; do not use.\cr
  583. \subheading{Comments:}
  584. @/* &^^{\>{@/}} Begin a long verbatim comment. ^^{comment!long!beginning}\cr
  585. @// &^^{\>{@/}} Begin a short verbatim comment.
  586. ^^{comment!short!beginning}\cr 
  587. @\% &^^{\>{@\PC}} An ignorable comment:  Everything to the next newline is
  588. completely ignored. ^^{comment!ignorable}\cr
  589. @? &^^{\>{@?}} Begin a compiler directive. ^^{compiler
  590. directives!beginning}\cr 
  591. @! &^^{\>{@"!}} Begin a compiler directive (obsolete). ^^{compiler
  592. directives!beginning}\cr 
  593. @( &^^{\>{@(}} Begin a meta-comment. ^^{comment!meta-!beginning}\cr
  594. @) &^^{\>{@)}} End a meta-comment. ^^{comment!meta-!ending}\cr
  595. \subheading{Special brace:}
  596. @\{ &^^{\>{@\LB}} Suppress default insertion of breakpoint command.
  597. ^^{breakpoint command!suppressing insertion of}\cr
  598. \subheading{Index entries:}
  599. @\UL &^^{\>{@\UL}} Force an index entry to be underlined.
  600. ^^{index!entry!underlining} \cr 
  601. @- &^^{\>{@-}} Delete an index entry for the next identifier.
  602. ^^{index!entry!deleting}\cr
  603. \medalign
  604. @\^ &^^{\>{@\^}} Make an index entry in Roman type. ^^{index!entry!Roman
  605. type}\cr  
  606. @. &^^{\>{@.}} Make an index entry in \.{typewriter} type.
  607. ^^{index!entry!typewriter type}\cr 
  608. @9 &^^{\>{@9}} Make an index entry in a format controlled by `\.{\\9}',
  609. which the user must define.
  610. ^^{index!entry!user-controlled format}\cr
  611. \subheading{Control text:}
  612. @t &^^{\>{@t}} Put control text into a \TeX\ \.{\\hbox}.
  613. ^^{text!control!putting into hbox}\cr
  614. @= &^^{\>{@=}} Pass control text verbatim to the output.
  615. ^^{text!control!passing verbatim to output}\cr
  616. \summarize{Control codes allowed in \WEB\ files, cont'd}{0.62}
  617. \subheading{Spacing:}
  618. @, &^^{\>{@,}} Insert a thin space. ^^{insertion!thin space}\cr
  619. @/ &^^{\>{@/}} Insert a line break. ^^{insertion!line break}\cr
  620. @| &^^{\>{@"|}} Insert an optional line break in an expression.
  621. ^^{insertion!optional line break}\cr
  622. @\# &^^{\>{@\PM}} Force a line break with some extra white space; very
  623. seldom necessary, since blank lines in the source are significant.  Also
  624. begin a preprocessor command. ^^{insertion!line break!with white space}\cr
  625. @+ &^^{\>{@+}} Cancel a line break. ^^{insertion!line break!cancelling}\cr
  626. @\amp &^^{\>{@\amp}} Join left and right with no spaces or line breaks
  627. inbetween. ^^{joining}\cr 
  628. \subheading{Pseudo (invisible) operators:}
  629. @e & Invisible (pseudo-) expression. ^^{pseudo-!expression}\cr
  630. @; &^^{\>{@;}} Invisible (pseudo-) semicolon. ^^{pseudo-!semicolon}\cr
  631. @: &^^{\>{@":}} Invisible (pseudo-) colon. ^^{pseudo-!colon}\cr
  632. \subsubsection Special format for language changes.
  633. The most general form of a language command is
  634. {\codemode
  635. @\It{[}L\It{]}\It{l}\math\,\math\It{text}[\It{options}]
  636. \noindent where $l$~is a language symbol, \It{text} is converted into a
  637. hyphenated option, and \It{options} have the same syntax as on the command
  638. line.  For example,
  639. {\codemode
  640. @n9[-n&]
  641. \noindent means set the language to \Fortran--90 and use free-form syntax
  642. with the ampersand as the continuation character.
  643. \summarize{Control codes allowed in change files}{0.62}
  644. ^^[change file!control codes] ^^[commands!control codes!in change file]
  645. The folllowing commands are allowed in change files. They \It{must} begin in
  646. column~1. Any line that does not begin with one of these commands is a comment.
  647. @x &^^{\>{@x}} Begin a change file entry.\cr
  648. @y &^^{\>{@y}} End the old code; begin the replacement code.\cr
  649. @z &^^{\>{@z}} End the change file entry.\cr
  650. \medalign
  651. @c &^^{\>{@c}} Set language to~C.^^{language!changing}\cr
  652. @c++ &^^{\>{@c++}} Set language to~\Cpp.^^{language!changing}\cr
  653. @n &^^{\>{@n}} Set language to \Fortran--77.\cr
  654. @n9 &^^{\>{@n9}} Set language to \Fortran--90.\cr
  655. @r &^^{\>{@r}} Set language to \Ratfor--77.\cr
  656. @r9 &^^{\>{@r9}} Set language to \Ratfor--90.\cr
  657. @L\It{l} &^^{\={@l}{@L{\it l}}} Set language to~$l$.\cr
  658. \medalign
  659. @[ &^^{\>{@[}} Switch into code mode.  (Use for column-oriented language
  660. such as \Fortran--77.)^^{code!mode}\cr 
  661. @] &^^{\>{@]}} Switch out of code mode.\cr
  662. \subsubsection The null change file.
  663. ^^[change file!null] ^^[file!null]
  664. When no change file is specified on the command line, the \WEB\ processors
  665. attempt to open and read from the so-called ``null file.''  (This file may or
  666. may not actually exist in the directory structure, depending on the
  667. system.)  The name of 
  668. this file, which is permanently empty, depends on the operating system and
  669. becomes the default value of 
  670. the style-file option \.{null\_file} according to the following table:
  671. $$\vbox{\offinterlineskip
  672. \halign{\vrule\vrule#&\strut\quad#\quad\hfil&\vrule#&\hfil\quad\tt#\quad\hfil
  673.     &\vrule\vrule#\cr\tablerule\tablerule
  674. &\It{Operating system}&&\It{Name of null file}&\cr
  675. \tablerule\tablerule 
  676. &IBM/PC&&nul&\cr\tablerule
  677. &IBM/MVS&&'NULLFILE'&\cr\tablerule
  678. &VAX/VMS&&nl:&\cr\tablerule
  679. &\Unix\ or other&&/dev/null&\cr\tablerule\tablerule
  680. Usually you must do nothing explicitly to access the null file.  However,
  681. if \FWEB\ can't find the default null file on your system, just create an
  682. empty file whose name is \It{null\_name} and insert into the style file the
  683. line ``\.{null\_file "}\It{null\_name}\.{"}''.
  684. \summarize{Commenting modes}{0.75}
  685. ^^[commenting style]
  686. ^^[mode!commenting] ^^{\CS{cmntfont}} ^^{\CS{tenrm}} 
  687. \FWEB\ allows a variety of commenting styles.  The visible comments are in
  688. the font \.{\\cmntfont}, which defaults to~\.{\\tenrm}.
  689. \subheading{Invisible comments:}
  690. @z...@x &^^{\>{@z}} ^^{\>{@x}} If a source or include file begins
  691. with~\atcmd{z}, then all material is skipped until and including a line
  692. beginning in column~1 with~\atcmd{x}.\cr
  693. @\% &^^{\>{@\PC}} All material until and including the next newline is
  694. completely ignored.\cr
  695. \subheading{Visible comments:}
  696. /*...*/ &^^{\>{/*...*/}} A long comment (may extend over several lines).
  697. ^^{comment!long}\cr
  698. //... &^^{\>{//...}} A short comment (terminated by next newline).  
  699. ^^{comment!short} 
  700. (In \Fortran\ 
  701. or \Ratfor, this must be turned on explicitly with one of the command-line
  702. options~`\.{-n/}', `\.{-r/}', or~`\hbox{\.{-/}}'.)\cr
  703. !... &^^{\>{"!...}} A short comment in \Fortran\ or \Ratfor.  This must be
  704. turned 
  705. on explicitly with one of the command-line options~`\.{-n!}', `\.{-r!}',
  706. or~`\.{-!}'.\cr
  707. !!... &^^{\>{"!"!...}} A short comment in \Fortran\ or \Ratfor.\cr
  708. @(...@) &^^{\>{@(}} A meta-comment.  The material between~\atcmd{(}
  709. and~\atcmd{)} is typeset in a verbatim environment, and is appropriately
  710. passed to the tangled output.  (See the style-file parameters \.{meta.*}.)
  711. ^^{comment!meta-}\cr
  712. \subsubsection Alternatives for `dot' commands in \Fortran\ and \Ratfor.
  713. ^^{input!alternative operators for}
  714. Although \Fortran\ and \Ratfor\ allow standard `dot' commands such
  715. as~`\.{.LT.}', they are considered to be obsolete; more modern alternatives
  716. are preferred.
  717. \input dots
  718. \subsubsection Considerations about formatting.
  719. ^^{formatting}
  720. The construction
  721. {\codemode
  722. @f \It{identifier} \It{old\_identifier}
  723. \medskip
  724. \noindent makes \It{identifier} behave like \It{old\_identifier}.  
  725. The \It{old\_identifier} may be one of the following special names,
  726. which insert extra spaces according to the positions of the underscores and
  727. behave as the part of speech indicated by the base names.  These are useful
  728. for dealing with macro constructions.
  729. {\codemode
  730. $_BINOP_
  731. $_COMMA_
  732. $_EXPR
  733. $_EXPR_
  734. $EXPR_
  735. $UNOP_
  736. When the current language is \.{TEX}, the format command can be used to
  737. change a category code according to the format
  738. {\codemode
  739. @f `\It{\TeX char} \It{new\_cat\_code}
  740. \summarize{Macro commands}{0.7}
  741. ^^[macros!command summary]
  742. Outer macros, defined by~\.{@d}, ^^{\>{@d}}
  743. are copied to the beginning of the output
  744. file. Inner \WEB\ macros are defined by~\.{@m}. ^^{\>{@m}}
  745. \WEB\ macro definitions in
  746. the definition section are collected at the beginning of the unnamed
  747. module. \WEB\ macro definitions in the code section (deferred definitions)
  748. become known when they are encountered while the code is being output.
  749. \medskip
  750. \WEB\ macro definitions have one of the following three forms:
  751. $$\def\args{{\tt(}args{\tt)} } 
  752. \tt\eqalignno{
  753.     \llap{@m } &\hbox{\it name\args text}\cr
  754.     \llap{@m* } &\hbox{\it name\args text}\cr
  755.     \llap{@m[bfimps*] } &\hbox{\it name\args text}\cr
  756. In the second form,
  757. the asterisk means that the macro may be recursive, ^^{macro!recursive}
  758. although \It{this feature is not implemented yet}.  In the third form,
  759. which is useful only for \Ratfor, ^^{\>{\Ratfor}}
  760. the brackets means that the contents of this macro
  761. are to be inserted automatically at the beginning of the type of program
  762. unit identified by the characters within the brackets.  ^^{automatic insertion}
  763. ^^{insertion!automatic}
  764. See the text for more information.
  765. \medskip
  766. Macros with a variable number of arguments are indicated by an 
  767. ellipsis ^^{ellipsis "(\noexpand\dots")}, as
  768. in `\atcmd{m\ VAR(x,y,z,...)\ \It{text}}'.
  769. \medskip
  770. Adjacent strings in macro text are automatically concatenated.
  771. ^^{strings!concatenating}
  772. \medskip
  773. The following special tokens can be used in the text of \WEB\ definitions.
  774. Here \It{parameter} means a dummy argument in the argument list of a
  775. function-like macro.
  776. \subheading{ANSI C-compatible tokens:}
  777. \#\# &^^{\>{\PM\PM}} Paste together tokens to left and right.
  778.  (ANSI~C-compatible.) ^^{token pasting}
  779.  \cr 
  780. \#\It{parameter} & Convert parameter to string, without expansion.
  781.  (ANSI~C-compatible.) ^^{stringizing}
  782. \subheading{Extensions to ANSI~C macro syntax:} ^^{extensions!to ANSI C
  783.  macro syntax} 
  784. \#*\It{parameter} &^^{\>{\PM*}} As above, but pass a quoted string through
  785.  unchanged.\cr 
  786. \#!\It{parameter} &^^{\>{\PM"!}} Don't expand argument.\cr
  787. \#'\It{parameter} &^^{\>{\PM'}} Convert parameter to a single-quoted
  788.  string, without expansion.\cr
  789. \#"\It{parameter} &^^{\>{\PM""}} Convert parameter to a double-quoted
  790.  string, without expansion.\cr
  791. \#0 & ^^{\>{\PM0}} The number of variable arguments.
  792.  ^^{macro!arguments!number of}
  793. \#\It{n} & ^^{\>{\PM}$n$} The $n^{\rm th}$ variable argument, counting
  794.  from~1.\cr 
  795. \#\{0\} & ^^{\>{\PM\LB0\RB}} Like~\.{\#0}, but the argument may be a macro or
  796. expression known at output time.\cr
  797. \#\{\It{n}\} & ^^{\>{\PM\LB$n$\RB}} Like~\.{\#$n$}, but the argument may be an
  798.  expression.\cr 
  799. \#[0] & ^^{\>{\PM[0]}} The total number of arguments (fixed plus
  800.  variable).  (The argument may be an expression.)\cr
  801. \#[\It{n}] & ^^{\>{\PM[$n$]}} The $n^{\rm th}$ argument (including the
  802.  fixed ones), counting from~1. (The argument may be an expression.)\cr
  803. \#. & ^^{\>{\PM.}} A comma-separated list of all variable arguments.\cr
  804. \#:0 &^^{\>{\PM":}} Unique statement number (expanded during phase~1).\cr
  805. \#:\It{nnn} & Unique statement number for each invocation of this macro
  806.  (expanded during phase~2).
  807.  ^^{statement!number}
  808. \#< &^^{\>{\PM<...@>}} Begin a section name.  (Ends with~\atcmd{>}.)
  809.  ^^{section name!beginning!in macro}
  810. \#, &^^{\>{\PM,}} An ``internal'' comma; does not delimit the end of an
  811.  argument.
  812. ^^{commas!as delimiters of macro arguments}
  813. ^^{commas!as part of a macro argument}
  814. {%\tracingall
  815. \summarize{Preprocessor commands}{0.7}
  816. ^^[commands!preprocessor!summary] ^^[preprocessing]
  817. \WEB\ preprocessor commands may appear in either the definition or the code
  818. part. But \It{beware}: No matter where they appear, they are expanded
  819. during \It{input}, not output.
  820. @\#define \Identifier\ &^^{\>{@\PM define}} Define a \WEB\ macro; equivalent
  821. to \atcmd{m}. ^^{\>{@m}} \cr 
  822. @\#undef \Identifier\ &^^{\>{@\PM undef}} Undefine a \WEB\ macro.\cr
  823. \medalign
  824. @\#ifdef \Identifier\ &^^{\>{@\PM ifdef}} Is \WEB\ macro defined? Equivalent to
  825. `\.{\If{} defined \Identifier}'.\cr
  826. @\#ifndef \Identifier\ &^^{\>{@\PM ifndef}} Is \WEB\ macro not defined?
  827. Equivalent to `\.{\If{} !defined \Identifier}'.\cr
  828. \medalign
  829. @\#if \expr^^{\>{@\PM if}}\cr
  830. @\#elif \expr^^{\>{@\PM elif}}\cr
  831. @\#else^^{\>{@\PM else}}\cr
  832. @\#endif^^{\>{@\PM endif}}\cr
  833. \summarize{Built-in \FWEB\ macros (A--K)}{0.55}
  834. ^^[macros!built-in!summary of]
  835. Built-in macros are expanded during output while processing the code part.
  836. They all begin with an underscore and are in upper case.
  837. \It{User-defined macros should not 
  838. begin with an underscore or a dollar sign.} In the following argument lists,
  839. \It{string} means a character string that should be surrounded
  840. by quotes.  In a few cases the quotes are optional if the argument is a
  841. single alphanumeric identifier, but don't use this property unless you
  842. really have to.
  843. \_A(\It{string}) &^^{\>{\UL A}} The built-in equivalent to~\.{@'\dots'}
  844. or~\.{@"\dots"}.  (Note the extra parentheses required by the built-in.)
  845. ^^{\>{@'}} ^^{\>{@""}}\cr
  846. \_ABS(\expr) &^^{\>{\UL ABS}} Absolute value of \expr.\cr
  847. \_ASSERT(\expr) &^^{\>{\UL ASSERT}} Evaluates \expr; if false, prints an error
  848. message and aborts.\cr
  849. \_COMMENT(\It{string}) &^^{\>{\UL COMMENT}} Generate a comment in the output
  850. file.\cr 
  851. \_DATE &^^{\>{\UL DATE}} A string consisting of the date in the form
  852. \.{"August\ 15,\ 1989"}.\cr 
  853. \_DAY &^^{\>{\UL DAY}} A string consisting of the day of the week in the form
  854.         \.{"Monday"}.\cr 
  855. \_DECR(N) &^^{\>{\UL DECR}} Decrement a macro.\cr
  856. \_DEFINE(defn) &^^{\>{\UL DEFINE}} Deferred macro definition.\cr
  857. \_DO(\It{macro},\It{imin},\It{imax}\It{[,$\Delta i$]}\{\dots\} &^^{\>{\UL
  858. DO}} Repetitively defines \It{macro} as would the \Fortran\ \&{do}~loop
  859. \.{do \It{macro} = \It{imin},\It{imax},$\Delta i$}.\cr
  860. \_DUMPDEF($m_1$,$m_2$,\dots) &^^{\>{\UL DUMPDEF}} Here $m_1$, $m_2$, etc.\
  861. are macro calls (with argument list if appropriate).  The macro definitions
  862. and their expansions are dumped to the terminal.\cr
  863. \_ERROR(\It{string}) &^^{\>{\UL ERROR}} Send \.{string} to the standard error
  864. message facility.\cr 
  865. \_EVAL(\expr) &^^{\>{\UL EVAL}} Evaluate a macro expression.\cr
  866. \_GETENV(\It{name}) &^^{\>{\UL GETENV}} Returns the present value of the
  867. environment variable \It{name}.^^{variable!environment}\cr
  868. \_HOME &^^{\>{\UL HOME}} The user's home directory; equivalent to
  869. \.{\_GETENV(HOME)}.\cr
  870. \_IF(\expr,$t$,$f$) &^^{\>{\UL IF}} Evaluates \expr. If true, returns~$t$;
  871. otherwise, returns~$f$.\cr 
  872. \_IFCASE(\It{expr},\It{case\_0},\dots,\It{case\_n},\It{dflt})
  873. &^^{\>{\UL IFCASE}} Evaluates \It{expr} to an integer~$m$. If $0 \le m \le n$,
  874. then \It{case\_m} is selected. Otherwise, the \It{dflt} is
  875. selected.\cr 
  876. \_IFDEF(\It{macro},$t$,$f$) &^^{\>{\UL IFDEF}} If \It{macro} is defined,
  877. returns~$t$; otherwise, returns~$f$.\cr
  878. \_IFNDEF(\It{macro},$t$,$f$) &^^{\>{\UL IFNDEF}} As above, but returns~$t$ if
  879. not defined.\cr 
  880. \_IFELSE(s1,s2,$t$,$f$) &^^{\>{\UL IFELSE}} Compares \.{s1} to \.{s2}. If
  881. identical, returns~$t$; otherwise, returns~$f$.\cr
  882. \_INCR(N) &^^{\>{\UL INCR}} Increment a macro.\cr
  883. \_INPUT\_LINE &^^{\>{\UL INPUT\UL LINE}} Line number (in \WEB\ source file)
  884. that begins current section.\cr
  885. \summarize{Built-in \FWEB\ macros (L--Z)}{0.55}
  886. \_L(\It{string}) &^^{\>{\UL L}} Changes \It{string} to lower case.\cr
  887. \_LANGUAGE &^^{\>{\UL LANGUAGE}} An identifier such as~`\.{\_C}'
  888. ^^{\>{\UL C}} ^^{\>{\UL CPP}}
  889. ^^{\>{\UL N}} ^^{\>{\UL N90}}
  890. ^^{\>{\UL R}} ^^{\>{\UL R90}}
  891. ^^{\>{\UL X}}
  892.     depending on the current language. (See the table below under
  893.     \.{\_LANGUAGE\_NUM}.) Intended 
  894.     to be used with an \.{\_IFELSE}.\cr 
  895. \_LANGUAGE\_NUM &^^{\>{\UL LANGUAGE\UL NUM}} An integer according to the
  896.     following table; intended to be used with an \.{\_IFCASE}.
  897.     \endgraf
  898.     \LANBUILTINS\cr
  899. \_LEN(string) &^^{\>{\UL LEN}} Length of (unexpanded) argument interpreted as a
  900. character string.\cr 
  901. \_M(defn) &^^{\>{\UL M}} Equivalent to \.{\_DEFINE}.\cr
  902. \_MAX($a$,$b$) &^^{\>{\UL MAX}} Maximum of the two expressions~$a$ and~$b$.\cr
  903. \_MIN($a$,$b$) &^^{\>{\UL MIN}} Minimum of~$a$ and~$b$.\cr
  904. \_MODULE\_NAME &^^{\>{\UL MODULE\UL NAME}} Name of present \WEB\ module.\cr
  905. \_MODULES &^^{\>{\UL MODULES}} The total number of \It{independent} modules:
  906. namely, the total number of independent module names, plus~1 for the
  907. unnamed module.\cr
  908. \_OUTPUT\_LINE &^^{\>{\UL OUTPUT\UL LINE}} Current line number of tangled
  909.     output.\cr 
  910. \_P &^^{\>{\UL P}} The C~preprocessor symbol~'\.{\#}'; a synonym for
  911. ``\.{\_UNQUOTE("\#")}''.\cr
  912. \_POW($x$,$y$) &^^{\>{\UL POW}} Exponentiation: $x^y$.\cr
  913. \_ROUTINE &^^{\>{\UL ROUTINE}} In \Ratfor\ mode, expands to a string built of 
  914. the name of the current program, function, or subroutine; not useful for other
  915. languages, for which it expands to the empty string.\cr
  916. \_SECTION\_NUM &^^{\>{\UL SECTION\UL NUM}} Number of current \WEB\ section.\cr
  917. \_SECTIONS &^^{\>{\UL SECTIONS}} The maximum section number as understood
  918. by \WEAVE.\cr 
  919. \_STRING(s) &^^{\>{\UL STRING}} Expands its argument, then stringizes it
  920. according to~\.{\#*}.\cr
  921. \_STUB(name) &^^{\>{\UL STUB}} References to undefined modules 
  922.     ^^{modules!undefined}
  923.     are automatically replaced by a call to this macro, with the module
  924.     name as argument.\cr
  925. %\_SWITCH() &^^{\>{\UL SWITCH}} \It{Not implemented yet}.\cr
  926. \_TIME &^^{\>{\UL TIME}} A string consisting of the local time in the form
  927. \.{"19:59"}.\cr 
  928. \_TRANSLIT(\It{string},\It{from},\It{to}) &^^{\>{\UL TRANSLIT}} Interprets
  929. all arguments as 
  930. character strings; replaces the \\{from} characters in~\\{s} by the
  931. corresponding \\{to}~characters.\cr 
  932. \_U(\It{string}) &^^{\>{\UL U}} Changes \It{string} to upper case.\cr
  933. \_UNDEF(\It{macro}) &^^{\>{\UL UNDEF}} Undefine a macro.\cr
  934. \_UNQUOTE(\It{string}) &^^{\>{\UL UNQUOTE}} Returns \It{string},
  935. without the surrounding quotes. \cr
  936. \_VERBATIM(\It{string}) &^^{\>{\UL VERBATIM}} Obsolete name for
  937. \.{\_UNQUOTE}.\cr 
  938. \_VERSION &^^{\>{\UL VERSION}} A string built out of the \.{FWEB} version
  939. number---e.g., \hbox{\.{"\FWEBversion"}}.\cr 
  940. \summarize{Ratfor\ commands}{0.5}
  941. ^^[Ratfor:\RATFOR!commands!summary of]
  942. Select \Ratfor--77 with~\atcmd{r} or~\atcmd{r7}; select \Ratfor--90
  943. with~\atcmd{r9}. 
  944. Disable \Ratfor\ statement translation with command-line option~`\.{-q}'
  945. (obsolete). In all cases, the construction~$\stmt$ can be replaced by a simple
  946. statement terminated by a semicolon.
  947. ^^{\>{-q}}
  948. \endgraf
  949. \subheading{Ratfor--77 commands:}
  950. break; &^^{\<{break}} Exit loop or \&{switch} immediately.\cr
  951. case $i$: &^^{\<{case}} Used only inside \&{switch}.\cr
  952. default:&^^{\<{default}} Used only inside \&{switch}.\cr
  953. do \dots; \stmt &^^{\<{do}} \Fortran's \&{do} statement. (The semicolon is
  954. required only when the \&{do} is followed by a simple statement; it is
  955. optional when followed by a left brace.)\cr
  956. else \stmt &^^{\<{else}} Used in conjunction with \&{if}.\cr
  957. for($a$;$b$;$c$) \stmt\ &^^{\<{for}} Execute~$a$. Test~$b$. If true,
  958. execute body. Execute~$c$. Test~$b$ again and iterate.\cr
  959. if(\cond) \stmt\ &^^{\<{if}} \Fortran's \&{if}\dots\&{then}.\cr
  960. next; &^^{\<{next}} Go to bottom of loop.\cr
  961. repeat \stmt\ until(\cond); &^^{\<{repeat}} Execute body. If \cond\ is
  962. true, iterate.\cr 
  963. return \expr; &^^{\<{return}} Return value from function.\cr
  964. switch(\expr) \stmt &^^{\<{switch}} Select various cases.  (Cases fall
  965. through unless terminated by \&{break}.)\cr
  966. while(\cond) \stmt\ &^^{\<{while}} If \cond\ is true, execute body of loop.\cr
  967. \subheading{Additional Ratfor--90 commands:}
  968. contains: &^^{\<{contains}} Note the colon.\cr
  969. interface \It{name} \stmt\ &^^{\<{interface}} Used as in \Fortran--90, but
  970. note the braces.\cr
  971. interface operator(\It{operator}) \stmt\ &As in \Fortran--90.\cr
  972. interface assignment(\It{assignment}) \stmt\ &As in \Fortran--90.\cr
  973. module \It{name} \stmt\ &^^{\<{module}} As in \Fortran--90.\cr
  974. private: &^^{\<{private}} Note the colon.\cr
  975. sequence: &^^{\<{sequence}} Note the colon.\cr
  976. type \It{name} \stmt; &^^{\<{type}} Note the semicolon.\cr
  977. where(\expr) \stmt\ &^^{\<{where}} \Fortran--90 array operations; may be
  978. followed by an optional \&{else} clause.\cr
  979. Caviats and nuances about \FWEB\ \Ratfor:
  980. ^^[\Ratfor!caviats]
  981. \newfeature
  982. \feature: Numeric statement labels must be followed by a colon; they should
  983. be first on their line.
  984. \feature: The quoting convention for characters and strings follows that
  985. of~C:  Single-quote single characters, double-quote strings.
  986. \feature: In a \&{switch}, cases fall through to the next case unless
  987. terminated by \&{break} (just as in~C).
  988. \feature: The \&{do} statement must be terminated by a semicolon if
  989. followed by a simple statement.  (It's unnecessary if followed by a left
  990. brace that begins a compound statement.)
  991. \feature: Use \.{\&\&} and~\.{||} for the logical AND and OR.
  992. \feature: Do not use an \&{end} statement at the very end of a program
  993. unit; it is added automatically when the closing brace is sensed.
  994. \def\TEXTs{sample\BS\_id}\def\TEXT{sample\_id}
  995. \summarize{Code mode and the principal {\tt fwebmac} typesetting macros}{0.5}
  996. ^^[macros!typesetting]
  997. The construction \.{\vertbar\dots\vertbar} signifies code mode; ^^{code!mode}
  998. it may be used in \TeX\ text 
  999. (including comments and module names) to typeset code or identifiers
  1000. between the bars.  When code mode is used, entries are made
  1001. in the index.  Alternatively, the following macros may be used; these do
  1002. not make entries in the index:
  1003. \BS Wtypewriter\{\TEXTs\} &^^{\CS{Wtypewriter}} Typeset in typewriter
  1004. type, such as ``\.{\TEXT}''.\cr 
  1005. \BS Wshort\{x\} &^^{\CS{Wshort}} Use for single-character identifiers,
  1006. such as~``\|x''.  (Do not use \WEB's shorthand notation~``\.{\\|x}'' 
  1007. ^^{\CS{"|}}
  1008. for this purpose, as the bar gets confused with the entry into code mode.)\cr
  1009. \BS Wid\{\TEXTs\} &^^{\CS{Wid}} Ordinary identifiers, such as
  1010. ``\\{\TEXT}''.\cr 
  1011. \BS Wreserved\{\TEXTs\} &^^{\CS{Wreserved}} For reserved words, such as
  1012. ``\&{\TEXT}''.\cr 
  1013. \BS Wintrinsic\{\TEXTs\} &^^{\CS{Wintrinsic}} For intrinsic functions,
  1014. such as ``\IF{\TEXT}''.\cr 
  1015. \noindent In the arguments of the above macros, you must precede the special
  1016. characters ``\.{\ \\\#\%\$\^\{\}\~\&\_}'' by a backslash.  
  1017. \medskip
  1018. For brevity, the above macros are equivalenced to shorter macros, as
  1019. follows:
  1020. \input equiv
  1021. \def\acd(#1){(\.{0x#1})}
  1022. \summarize{Escape sequences}{0.5}
  1023. ^^[escape sequences]
  1024. \FWEB\ follows ANSI~C in recognizing the following escape sequences within
  1025. strings. (The corresponding \&{ASCII} code is in parentheses.)
  1026. \BS' \acd(27) & \It{Literal apostrophe}.\cr
  1027. \BS" \acd(22) & \It{Literal quotation mark}.\cr
  1028. \BS?$\vphantom{a}$ \acd(3F) & \It{Literal question mark}.\cr
  1029. \BS\BS\ \acd(5C) & \It{Literal backslash}.\cr
  1030. \BS a \acd(07) & \It{Alert}---ring the bell or print visual alert.\cr
  1031. \BS b \acd(08) & \It{Horizontal backspace}.\cr
  1032. \BS f \acd(0C) & \It{Form feed}---force output device to begin a new page.\cr
  1033. \BS n \acd(0A) & \It{Newline}---move to next line.\cr
  1034. \BS r \acd(0D) & \It{Carriage return}---move to beginning of line.\cr
  1035. \BS t \acd(09) & \It{Horizontal tab}---move to next tab mark.\cr
  1036. \BS v \acd(0B) & \It{Vertical tab}---move to next tab mark.\cr
  1037. \BS \It{NNN} & \It{Octal number}.\cr
  1038. \BS x\It{NN} & \It{Hexadecimal number}.\cr
  1039. \summarize{Conventions for \FWEAVE's identifiers}{0.7}
  1040. Following are the interpretation of the various fonts used in the output
  1041. produced by \FWEAVE.  Subscripts mean the number of the section in which the
  1042. identifier was defined.  In the index, underlined section numbers mean the
  1043. identifier was defined there.
  1044. \subheading{Automatically-generated entries:}
  1045. {\it italics} & An ordinary identifier such as~\|x or~\\{xyz}.\cr
  1046. {\it mark\/}$\WIN0{90}$ & An identifier explicitly marked with~\.{@[}.\cr
  1047. {\it name\/}$\WIN1{91}$ & A function name such as \\{main} defined in
  1048. section~98.\cr 
  1049. {\it inner\/}$\WIN2{92}$ & A \WEB\ macro.\cr
  1050. {\it outer\/}$\WIN3{93}$ & An outer macro.\cr
  1051. {\bf boldface} & A reserved word such as \&{integer}.\cr
  1052. {\bf newtype}$\WIN5{95}$ & A new type created via \&{typedef}.\cr
  1053. {\bfit boldfaced italic} & An intrinsic function such as \IF{sin}.\cr
  1054. {\tt TYPEWRITER} & A \Fortran\ keyword such as \.{BLOCKSIZE}. (These must
  1055. be in upper case.)\cr
  1056. \subheading{User-defined entries:}
  1057. {\tt typewriter} &\.{@.\dots@>}\cr
  1058. {\rm Roman} &\.{@\^\dots@>}\cr
  1059. {\ss user-defined} &\.{@9\dots@>}.  For example, to make an index entry in
  1060. {\ss sans serif} type say ``\.{\\def\\9\#1\{\{\\tenss\#\}\}}''.\cr
  1061. \summarize{Special array processing}{0.7}
  1062. In \Fortran\ and \Ratfor, \FTANGLE\ replaces left and right square brackets 
  1063. (outside of strings) by left and right parentheses.  Thus, brackets can be
  1064. used for array subscripts if one desires.
  1065. \medskip
  1066. When the option `\.{-W[}' is used, \FWEAVE\ replaces square brackets by a
  1067. special \TeX\ macro.  To change the appearance of array indices, redefine
  1068. the macro \.{\\WARRAY}.  ^^{\CS{WARRAY}}
  1069. For example, to subscript indices, say ``\.{\\let \\WARRAY\\WSUB}''.
  1070. \par\par
  1071. ^^{\CS{WSUB}}
  1072. ^^)syntax!summary)
  1073. \appendix M:  CUSTOMIZING via the STYLE FILE.[][20.13.11]
  1074. The default name of the style file is \.{fweb.sty}; ^^{\>{fweb.sty}}
  1075. change that with the
  1076. `\.{-z}'~command-line option.  ^^{\>{-z}}
  1077. \TeX-like comments (beginning with~'\.{\%}') may be included.
  1078. An alphabetized list of the vocabulary commands may be found in the index
  1079. under ``\.{style file, vocabulary}''.
  1080. The command syntax is
  1081. {\codemode
  1082. \It{keyword [=] value}
  1083. \medskip
  1084. \noindent For example,
  1085. {\codemode
  1086. LaTeX.options = "eqalign"
  1087. \medskip
  1088. The style-file parameters are user-specific.  The local style file 
  1089. is intended to be used for changes that are run-specific.  (Contrast that
  1090. with the initialization file \.{.fweb}, ^^{\>{.fweb}}
  1091. which is intended to set the user's
  1092. default environment for all runs.)  Style-file parameters that are intended
  1093. to permanently override \FWEB's defaults should be put into \.{.fweb} by
  1094. using the `\.{+p}'~option. ^^{\>{-p}}
  1095. A mechanism is also provided to aid in installation-wide customization
  1096. ^^{customization!installation-wide}
  1097. done when \FWEB\ is compiled. This
  1098. is explained in the separate documentation about installation and in the
  1099. source file \.{custom.web}. ^^{\>{custom.web}}
  1100. \def\stylehook#1{\subsubsection #1.\par
  1101.     \let\subtitle\empty
  1102.     \kern-\baselineskip}
  1103. \input index.stl
  1104. \input modules.stl
  1105. \input contents.stl
  1106. \input subs.stl
  1107. \input formats.stl
  1108. \input wmisc.stl
  1109. \input t.stl
  1110. \input wtmisc.stl
  1111. \input auto.stl
  1112. \input colors.stl
  1113. \input ccodes.stl
  1114. \appendix N:  MEMORY ALLOCATION.[]
  1115. ^^(memory, dynamic allocation of!summary(
  1116. The command-line option~`\.{-y}' ^^{\>{-y}} ^^{statistics}
  1117. is used to change the default allocation
  1118. for a dynamic memory array, as in~`\.{-ym4000}'.  To query the present
  1119. allocations of variable~\It{aa}, where \It{aa}~is the abbreviation in the
  1120. list below, just say ``\.{-y\It{aa}}'' with no
  1121. numeric argument.  To query everything, say ``\.{-y}''.  
  1122. The option~`\.{-s}' ^^{\>{-s}}
  1123. reports memory-usage statistics at the end of the run.  
  1124. The option~`\.{-sm\It{[n]}}' ^^{\>{-sm}}
  1125. reports allocations of~$n$ or more bytes as they
  1126. occur.  If $n$~is omitted, $n = 10000$ is assumed.
  1127. \medskip
  1128. Here is a brief discussion \It{(not completed yet!)}
  1129. of the dynamic arrays and their abbreviations.  (For more information,
  1130. please study the code.)  
  1131. $$\def\var#1 (#2){\\{#1}~(\.{"#2"})}
  1132. \vbox{\halign{\var #\hfil&\ ---\
  1133.         \vtop{\hsize=0.65\hsize\noindent\hang\strut#\strut}\hfil\cr
  1134. buf\_size (bs)&Size of the change buffer.\cr
  1135. C\_buf\_size (cb)&Buffer size for single-character buffered output in~C.\cr
  1136. cmd\_fmt\_size (cf)&Buffer size for certain output messages in \Ratfor.\cr
  1137. cmd\_msg\_size (cg)&As above.\cr
  1138. delta\_dots (d)&Number of additional entries to reallocate for the \\{dots}
  1139.  array if necessary.\cr
  1140. line\_length (ll)&Line length for \FWEAVE's output. \cr
  1141. longest\_name (ln)&Module names or strings shouldn't be longer than
  1142.  this.\cr
  1143. max\_bytes (b)&Maximum number of bytes in identifiers, index entries, and
  1144.  module names.\cr 
  1145. max\_dtexts (dx)&Maximum number of deferred replacement texts.\cr
  1146. max\_dtoks (dt)&Maximum number of tokens in \FTANGLE's deferred macro pool.\cr
  1147. max\_expr\_chars (lx)&Maximum length of expressions for compound
  1148.  assignments.\cr 
  1149. max\_lbls (lb)&Maximum nesting level in \Ratfor.\cr
  1150. max\_modules (m)&Must be larger than the maximum number of modules.\cr
  1151. max\_names (n)&Maximum number of identifiers, strings, and module names.\cr
  1152. max\_refs (r)&Maximum number of cross-references.\cr
  1153. max\_scraps (s)&Maximum number of scraps during \FWEAVE's parsing.\cr
  1154. max\_texts (x)&Maximum number of replacement texts for \FTANGLE.\cr
  1155. max\_toks (tt)&Maximum number of tokens in \FTANGLE's compressed code.\cr
  1156. max\_toks (tw)&Maximum number of tokens in current code text being parsed by
  1157.  \FWEAVE.\cr
  1158. mbuf\_size (mb)&Size of the area into which macros are expanded. This must
  1159.  be large enough to hold all intermediate levels of expansion as well as the
  1160.  final result. Furthermore, in some complicated situations, especially in
  1161.  \Ratfor, more than one macro buffer can be open at once.\cr
  1162. num\_files (nf)&Number of open files, especially for the \.{@o}~command.\cr
  1163. op\_entries (op)&Size of the table that handles overloaded operators.  A
  1164.  fixed table of length~128 is always used to handle operators such
  1165.  as~`\.{=}'.  The 
  1166.  quantity \\{op\_entries} must be greater than that amount by the number of
  1167.  new names that are explicitly overloaded.\cr
  1168. sbuf\_len (sb)&Length of input line buffer for style file.\cr
  1169. stack\_size (kt)&\FTANGLE's stack size.\cr
  1170. stack\_size (kw)&\FWEAVE's stack size.\cr
  1171. X\_buf\_size (xb)&Size of \TeX's output buffer.\cr
  1172. Thus, for example, to set the maximum number of modules to be 4000, say
  1173. ``\.{-ym4000}''. 
  1174. ^^)memory, dynamic allocation of!summary)
  1175. \appendix O:  CHARACTER SETS.[][19.15.2]
  1176. \FWEB\ works internally with the ASCII character set.  Users of some IBM
  1177. machines may need to be familiar with the EBCDIC character set as well.
  1178. \subsubsection The ASCII character set.
  1179. ^^(character!set!ASCII(
  1180. Here is the ASCII character set, shown in octal, decimal, and hexadecimal.  The
  1181. escape sequences recognized by~C and~\FWEB\ are also shown where
  1182. appropriate.  [This table is a minor modification of that given in the
  1183. excellent book by the Mark Williams Company, {\sl ANSI~C:  A Lexical Guide}
  1184. (Prentice Hall, Englewood Cliffs, New Jersey, 1988), p.~66.]
  1185. \rm\def\ANSI#1\par{\smallbreak
  1186. $$\def\ctrl##1{$\langle${\bf ctrl--{\tt##1}}$\rangle$\ }
  1187. \vbox{\halign{\hfil0##\unskip\qquad&\hfil##\unskip\qquad
  1188. &\hfil0x\tt##\unskip\qquad&\hfil\tt##\unskip\qquad
  1189. &\vtop{\hsize=0.5\hsize 
  1190. \noindent\hang\strut##\strut}\hfil\cr#1}}$$\vfill\eject}
  1191. \ANSI
  1192. 00 & 0 & 00 & NUL & \ctrl{@} Null character\cr
  1193. 01 & 1 & 01 & SOH & \ctrl{A} Start of header\cr
  1194. 02 & 2 & 02 & STX & \ctrl{B} Start of text\cr
  1195. 03 & 3 & 03 & ETX & \ctrl{C} End of text\cr
  1196. 04 & 4 & 04 & EOT & \ctrl{D} End of transmission\cr
  1197. 05 & 5 & 05 & ENQ & \ctrl{E} Enquiry\cr
  1198. 06 & 6 & 06 & ACK & \ctrl{F} Positive acknowledgement\cr
  1199. 07 & 7 & 07 & BEL & \ctrl{G} Alert (``bell'') (\.{'\\a'})\cr
  1200. 10 & 8 & 08 & BS & \ctrl{H} Backspace (\.{'\\b'})\cr
  1201. 11 & 9 & 09 & HT & \ctrl{I} Horizontal tab (\.{'\\t'})\cr
  1202. 12 & 10 & 0A & LF & \ctrl{J} Line feed (``newline'') (\.{'\\n'})\cr
  1203. 13 & 11 & 0B & VT & \ctrl{K} Vertical tab (\.{'\\v'})\cr
  1204. 14 & 12 & 0C & FF & \ctrl{L} Form feed (\.{'\\f'})\cr
  1205. 15 & 13 & 0D & CR & \ctrl{M} Carriage return (\.{'\\r'})\cr
  1206. 16 & 14 & 0E & SO & \ctrl{N} Shift out\cr
  1207. 17 & 15 & 0F & SI & \ctrl{O} Shift in\cr
  1208. 20 & 16 & 10 & DLE & \ctrl{P} Data link escape\cr
  1209. 21 & 17 & 11 & DC1 & \ctrl{Q} Device control 1 (XON)\cr
  1210. 22 & 18 & 12 & DC2 & \ctrl{R} Device control 2 (tape on)\cr
  1211. 23 & 19 & 13 & DC3 & \ctrl{S} Device control 3 (XOFF)\cr
  1212. 24 & 20 & 14 & DC4 & \ctrl{T} Device control 4 (tape off)\cr
  1213. 25 & 21 & 15 & NAK & \ctrl{U} Negative acknowledgement\cr
  1214. 26 & 22 & 16 & SYN & \ctrl{V} Synchronize\cr
  1215. 27 & 23 & 17 & ETB & \ctrl{W} End of transmission block\cr
  1216. 30 & 24 & 18 & CAN & \ctrl{X} Cancel\cr
  1217. 31 & 25 & 19 & EM & \ctrl{Y} End of medium\cr
  1218. 32 & 26 & 1A & SUB & \ctrl{Z} Substitute\cr
  1219. 33 & 27 & 1B & ESC & \ctrl{[} Escape\cr
  1220. 34 & 28 & 1C & FS & \ctrl{\BS} Form separator\cr
  1221. 35 & 29 & 1D & GS & \ctrl{]} Group separator\cr
  1222. 36 & 30 & 1E & RS & \ctrl{\^} Record separator\cr
  1223. 37 & 31 & 1F & US & \ctrl{\_} Unit separator\cr
  1224. \ANSI
  1225. 40 & 32 & 20 & \.{\ } & Space\cr
  1226. 41 & 33 & 21 & {!} & Exclamation point\cr
  1227. 42 & 34 & 22 & " & Quotation mark (\.{'\\"'})\cr
  1228. 43 & 35 & 23 & \# & Pound (sharp) sign\cr
  1229. 44 & 36 & 24 & \$ & Dollar sign\cr
  1230. 45 & 37 & 25 & \% & Percent sign\cr
  1231. 46 & 38 & 26 & \amp & Ampersand\cr
  1232. 47 & 39 & 27 & ' & Apostrophe (right quote) (\.{'\\''})\cr
  1233. 50 & 40 & 28 & ( & Left parenthesis\cr
  1234. 51 & 41 & 29 & ) & Right parenthesis\cr
  1235. 52 & 42 & 2A & * & Asterisk\cr
  1236. 53 & 43 & 2B & + & Plus sign\cr
  1237. 54 & 44 & 2C & , & Comma\cr
  1238. 55 & 45 & 2D & - & Hyphen (minus sign)\cr
  1239. 56 & 46 & 2E & {.} & Period\cr
  1240. 57 & 47 & 2F & / & Virgule (slash)\cr
  1241. 60 & 48 & 30 & 0\cr
  1242. 61 & 49 & 31 & 1\cr
  1243. 62 & 50 & 32 & 2\cr
  1244. 63 & 51 & 33 & 3\cr
  1245. 64 & 52 & 34 & 4\cr
  1246. 65 & 53 & 35 & 5\cr
  1247. 66 & 54 & 36 & 6\cr
  1248. 67 & 55 & 37 & 7\cr
  1249. 70 & 56 & 38 & 8\cr
  1250. 71 & 57 & 39 & 9\cr
  1251. 72 & 58 & 3A & {:} & Colon\cr
  1252. 73 & 59 & 3B & ; & Semicolon\cr
  1253. 74 & 60 & 3C & $<$ & Less-than (left angle bracket)\cr
  1254. 75 & 61 & 3D & $=$ & Equal sign\cr
  1255. 76 & 62 & 3E & $>$ & Greater-than (right angle bracket)\cr
  1256. 77 & 63 & 3F & {?} & Question mark (\.{'\\?'})\cr
  1257. \ANSI
  1258. 100 & 64 & 40 & {@} & At sign\cr
  1259. 101 & 65 & 41 & A\cr
  1260. 102 & 66 & 42 & B\cr
  1261. 103 & 67 & 43 & C\cr
  1262. 104 & 68 & 44 & D\cr
  1263. 105 & 69 & 45 & E\cr
  1264. 106 & 70 & 46 & F\cr
  1265. 107 & 71 & 47 & G\cr
  1266. 110 & 72 & 48 & H\cr
  1267. 111 & 73 & 49 & I\cr
  1268. 112 & 74 & 4A & J\cr
  1269. 113 & 75 & 4B & K\cr
  1270. 114 & 76 & 4C & L\cr
  1271. 115 & 77 & 4D & M\cr
  1272. 116 & 78 & 4E & N\cr
  1273. 117 & 79 & 4F & O\cr
  1274. 120 & 80 & 50 & P\cr
  1275. 121 & 81 & 51 & Q\cr
  1276. 122 & 82 & 52 & R\cr
  1277. 123 & 83 & 53 & S\cr
  1278. 124 & 84 & 54 & T\cr
  1279. 125 & 85 & 55 & U\cr
  1280. 126 & 86 & 56 & V\cr
  1281. 127 & 87 & 57 & W\cr
  1282. 130 & 88 & 58 & X\cr
  1283. 131 & 89 & 59 & Y\cr
  1284. 132 & 90 & 5A & Z\cr
  1285. 133 & 91 & 5B & {[} & Left bracket\cr
  1286. 134 & 92 & 5C & \ttBS & Backslash (\.{'\\\\'})\cr
  1287. 135 & 93 & 5D & {]} & Right bracket\cr
  1288. 136 & 94 & 5E & {\^} & Circumflex\cr
  1289. 137 & 95 & 5F & \_ & Underscore\cr
  1290. \ANSI
  1291. 140 & 96 & 60 & \.{\`} & Grave (left quote)\cr
  1292. 141 & 97 & 61 & a\cr
  1293. 142 & 98 & 62 & b\cr
  1294. 143 & 99 & 63 & c\cr
  1295. 144 & 100 & 64 & d\cr
  1296. 145 & 101 & 65 & e\cr
  1297. 146 & 102 & 66 & f\cr
  1298. 147 & 103 & 67 & g\cr
  1299. 150 & 104 & 68 & h\cr
  1300. 151 & 105 & 69 & i\cr
  1301. 152 & 106 & 6A & j\cr
  1302. 153 & 107 & 6B & k\cr
  1303. 154 & 108 & 6C & l\cr
  1304. 155 & 109 & 6D & m\cr
  1305. 156 & 110 & 6E & n\cr
  1306. 157 & 111 & 6F & o\cr
  1307. 160 & 112 & 70 & p\cr
  1308. 161 & 113 & 71 & q\cr
  1309. 162 & 114 & 72 & r\cr
  1310. 163 & 115 & 73 & s\cr
  1311. 164 & 116 & 74 & t\cr
  1312. 165 & 117 & 75 & u\cr
  1313. 166 & 118 & 76 & v\cr
  1314. 167 & 119 & 77 & w\cr
  1315. 170 & 120 & 78 & x\cr
  1316. 171 & 121 & 79 & y\cr
  1317. 172 & 122 & 7A & z\cr
  1318. 173 & 123 & 7B & \{ & Left brace\cr
  1319. 174 & 124 & 7C & | & Vertical bar\cr
  1320. 175 & 125 & 7D & \} & Right brace\cr
  1321. 176 & 126 & 7E & $\sim$ & Tilde\cr
  1322. 177 & 127 & 7F & DEL & Delete\cr
  1323. ^^)character!set!ASCII)
  1324. \subsubsection The EBCDIC character set.
  1325. ^^(character!set!EBCDIC(
  1326. \It{This will be completed someday.}
  1327. ^^)character!set!EBCDIC)
  1328. \appendix P: INDEX.[]
  1329. The page numbers in the index for this manual can appear in a variety of
  1330. fonts. These have the following meaning:
  1331. $$\vbox{\halign{#\hfil&\ ---\ #\hfil\cr
  1332. Roman&The keyword or phrase is {mentioned} here.\cr
  1333. $\underline{\hbox{Roman}}$&$\underline{\hbox{Definition}}$ of concept or
  1334.     keyword.\cr 
  1335. {\bf boldfaced}&Reference to an entire {\bf topic}.\cr
  1336. {\it italics}&An \It{example} is given.\cr}
  1337. ^^{type|see{fonts}}
  1338. \let\underline\relax
  1339. \Wcon % Print table of contents.
  1340.